Unit Description:
––––––––––––––––––––––––

The About… Unit was written by Jon Wind, to provide a simple, drop-in means of creating a modal or modeless TEXT display system suitable for online styled help.  About… is copyrighted, and I reserve all rights to it.

About… is SHAREWARE.  It’s fully functional and has no time limit.  Bear this in mind when you are deciding whether or not to pay me for its use.  It’s a simple concept.  If you use it, pay for it.  I trust you.  Please don’t rip me off.

Your one-time usage fee of $10 delivers a diskette containing the Think Pascal source (and a few other goodies) and entitles you to use this and future versions of About… in any program or programs you write and/or distribute.  You need not credit me for its use.

Special Features Include:
––––––––––––––––––––––––

• Requires only a Mac Plus (128K ROMs).

• Ability to select any of 6 modal window types: dBoxProc, plainDBox, altDBoxProc, noGrowDocProc, rDocProc, or movableDBoxProc.  If the movableDBoxProc is not available in the current System, the noGrowDocProc is used instead.

• Ability to use any size window provided it’s at least 100 (v) by 150 (h) pixels.  If the window is being centered, it must also be able fit on the main monitor.

• Ability to select the Font, Size, Face, and Color used by the TEXT and message.  Any of the 8 standard QuickDraw colors are available: whiteColor, redColor, greenColor, blueColor, cyanColor, magentaColor, yellowColor, or blackColor.

• Optional use of styled text on machines which support this feature and have enough available memory, overriding the Font, Size, Face, and Color defined in the AboutRec.

• Optional display of a user specified message and/or ICON.  A second icon (drawn in place of the original icon) and/or a second message (drawn in place of the original message) may also be specified.  These are displayed when the user clicks on the original icon.  Color icons are used if Color QuickDraw and ‘cicn’ resources with the same IDs are available.  If no icon is specified and the length of the user specified message is 0 characters then the OK button is centered.

• Automatic use of the application’s (or System’s) default control and window color tables.

• Automatic disabling of the OK button and graying of the default roundrect when the window is not in front.

• Optional centering of the window on the top-most window or on the main screen.  If told to center on the front window and no window is visible, it will try to center it on the main screen.  Windows are placed slightly higher when centering on the screen.  When centering, About… endeavors to keep the window visible, shifting it as needed.

• Optional use of a close box instead of an OK button for noGrowDocProc or rDocProc windows.  If no icon is specified and the length of the user specified message is 0 characters then the scrolling text area is expanded to use the entire window.

• Optional copying to the clipboard of the current text by pressing command-c.  If styled text is in use, the style information is also copied.

• Optional keyboard equivalents for scrolling.  These include directional arrows, <, >, and Page Up, Page Down, Home, and End keys on the extended keyboard.  If the command key is down when the arrow keys or > or < is pressed, scrolling is by page.

• Keyboard equivalents for selecting the OK button are supported.  These include return, enter and, optionally, o, O, and command-o.

• Windows are modal or modeless, depending on which About… unit is used.  Windows with title bars may be dragged and, when running under MultiFinder, it’s possible to switch to other programs (except when the dBoxProc window type is used).  Dragging with the command key down will move a non-modal window without bringing it to the front.

• Option-clicking in a window displays the About… version number.

Usage Instructions:
––––––––––––––––––––––––

To use About… in your program, you’ll need to add the ‘About.lib’ and ‘AboutIntf.p’ files to your project.  Then add ‘About’ to the Uses clause in each file that uses one of the About… calls.

About… requires a resource of type ‘TEXT’ and, optionally, a resource of type ‘styl’ (with the same ID as the TEXT resource) in the current resource file.  The TEXT resource is simply free text.  The easiest way to create this resource is to copy text to the clipboard and paste it into a resource file using ResEdit.  The styl resource describes the styles used within the text.  The easiest way to create this resource is to use ResEdit 2.1, open the TEXT resources and simply apply styles to the text.  ResEdit will automatically create a styl resource if styles are applied to the text.

To display your TEXT in a modal window, create a variable of type AboutRec (making sure to define all fields) and then call the procedure BuildAbout.  If the TEXT resource cannot be loaded, the window is too large or small, or the window type is not supported, the speaker will sound and no window will be built; otherwise BuildAbout displays the window and takes over until the user dismisses it.

   ROCEDURE BuildAbout(WinRect : Rect;
                       inProc, TEXTid : Integer;
                       inTitle, WinMsg : Str255;
                       inMisc : AboutRec);

Modeless windows require a bit more work on the part of the programmer.  To display your TEXT in a modeless window, create a variable of type AboutRec (making sure to define all fields) and then call the function OpenAbout.  If the TEXT resource cannot be loaded, the window is too large or small, or the window type is not supported, the speaker will sound, no window will be built, and NIL will be returned; otherwise a pointer to the window will be returned.

   ROCEDURE OpenAbout(WinRect : Rect;
                      inProc, TEXTid : Integer;
                      inTitle, WinMsg : Str255;
                      inMisc : AboutRec) : WindowPtr;

After creating the modeless window, simply call the HandleAbout procedure for each open About… modeless window after every event.  It takes care of updating, keypresses, clicks, drags, activating, deactivating, etc.

   ROCEDURE HandleAbout(var theWindow : WindowPtr;
                       var theEvent : EventRecord);

The modeless window may be closed by the user in the HandleAbout procedure or by the calling program by using the CloseAbout procedure.

   ROCEDURE CloseAbout(var theWindow : WindowPtr);

Also included for use with modeless windows is the IsAbout function which returns True if the specified window is an About… window and False if it is not.  This makes it easy to determine if an event needs to be sent to HandleAbout for that window.

   ROCEDURE IsAbout(theWindow : WindowPtr);

Usage Tips:
––––––––––––––––––––––––

About… was designed to be easily integrated into any program.  Nonetheless, it does need a certain amount of help to work transparently.

First, always give About… as much information as possible.  This means defining all fields in the AboutRec and calling HandleAbout for each open About… modeless window after every event.  When using modeless windows, you may wish to modify the EventRecord before passing it to HandleAbout.  For instance, if a program allows the user to dismiss a window by pressing the escape key, you can change the escape keypress to an enter keypress in the EventRecord and pass the modified record to HandleAbout.

Second, remember that a modal window created with BuildAbout is also handled entirely by BuildAbout.  If a window in the current application is revealed by dragging the About… window, that window won’t be updated, since About… doesn’t know how to update it.  Windows revealed in underlying applications will be updated, however.

Third, because About… uses TextEdit to display text, it’s only as stable as TextEdit.  When memory is tight, certain TextEdit operations will fail (often without warning), causing a system bomb.  About… tries very hard to avoid these situations, but it is a good practice to check whether there is sufficient memory available for the window and its text before asking About… to create it.

Info/Feedback:
––––––––––––––––––––––––

If you’d like to offer some feedback, have questions, or want to send me money, I’d like to hear from you.  I can be reached at:

COMPUSERVE: 70167,3444
GENIE: JPWIND
MCIMAIL: JWIND
AMERICA ONLINE: JWIND

Jon Wind (About…)
2374 Hillwood Drive
Maplewood, MN  55119